APIs & Integrations

XMPP

Structr can take part in XMPP conversations as a user of an XMPP server. XMPP, also known as Jabber, is an open protocol for chat and presence, and many organizations run their own server for it. Your application can send messages to people, react to messages it receives, take part in chat rooms, and manage the contacts of its account.

Typical uses are notifications that reach people in the chat client they already use, chat bots that answer questions with data from your application, and rooms where your application posts events for a team.

If you want to exchange data with other systems rather than with people, use a message broker instead, see Message Brokers.

The XMPPClient

An XMPPClient object represents an account on an XMPP server. You create it like any other object, in the Data area of the Admin UI or with $.create() in a script. When you enable it, Structr logs in to the server with the account and keeps the connection open in the background. If the connection is lost, for example because the server restarts, Structr tries to restore it every five seconds. If the server ends the session on purpose, or the client cannot log in, for example because of a wrong password, Structr does not try again. Enabled clients connect again when Structr starts.

Encryption

Structr only connects to servers that encrypt the connection with TLS, because the password of the account and every message would otherwise travel in plain text. The server must offer TLS on the connection, and its certificate must be issued for the XMPP domain in xmppService and be trusted by the Java runtime of Structr. A certificate from a public certificate authority works without further setup. For a certificate of your own, add it or the certificate of its authority to the trust store of the Java runtime.

Setting Up a Client

let client = $.create('XMPPClient', {
    name: 'Notifications',
    xmppUsername: 'structr',
    xmppPassword: 'secret',
    xmppService: 'example.com',
    xmppHost: 'xmpp.example.com',
    xmppPort: 5222,
    isEnabled: true
});

After the client has logged in, it announces its presence, because the server delivers messages to an account only while it is available. Messages that the server kept while the client was offline arrive at that point.

The connection settings take effect when the client connects. To apply changes to them, disable the client and enable it again.

Receiving Messages

To react to incoming messages, add a method named onXMPPMessage to the type XMPPClient in the schema. Structr calls it for every message with a text that the client receives, both direct messages and messages in chat rooms the client has joined. The method receives two arguments:

$.this is the client that received the message, so the method can answer directly:

// method onXMPPMessage of the type XMPPClient
{
    if ($.arguments.message.trim() === 'status') {

        let open = $.find('Ticket', { status: 'open' }).length;

        $.this.doSendMessage({ recipient: 'alice@example.com', message: open + ' open tickets' });
    }
}

The client also receives the messages that it sends to a chat room, because the room distributes them to all occupants, the sender included. A method that answers messages in a room should therefore ignore its own.

Sending Messages

The method doSendMessage sends a message to an address:

client.doSendMessage({ recipient: 'alice@example.com', message: 'The nightly import has finished.' });

Like every method called from JavaScript, the methods of the client take their arguments as an object with names.

Chat Rooms

Chat rooms let several people and applications talk in one place. A room has an address of its own, usually in a separate domain of the server, e.g. team@conference.example.com.

client.doJoinChat({ chatRoom: 'team@conference.example.com', nickname: 'Structr' });
client.doSendChatMessage({ chatRoom: 'team@conference.example.com', message: 'Deployment finished.' });

Joining a room waits for the answer of the server, so doJoinChat reports an error to your script if the server refuses, for example because of a wrong password.

When a lost connection is restored, the client joins its rooms again. After a restart of Structr, or when you disable and enable the client, it is no longer in any room and receives no room messages until it joins again. doSendChatMessage joins on its own, but a client that only listens to a room has to join it again. Since doJoinChat does nothing for a room the client is in already, you can call it regularly, for example in a scheduled method.

Contacts and Subscriptions

In XMPP, an account sees whether another account is available only if it has subscribed to it, and the other account has to confirm the subscription. This is how both sides of a chat end up in each other’s contact list.

To answer requests that other accounts send to your client, add a method named onXMPPPresence to the type XMPPClient. Structr calls it for subscription requests and answers with two arguments:

// method onXMPPPresence of the type XMPPClient
{
    if ($.arguments.type === 'subscribe') {

        if ($.arguments.sender.endsWith('@example.com')) {

            $.this.doConfirmSubscription({ recipient: $.arguments.sender });

        } else {

            $.this.doDenySubscription({ recipient: $.arguments.sender });
        }
    }
}

Without an onXMPPPresence method, Structr rejects every subscription request, so that it does not stay pending. If the method fails with an error, the request stays pending, and the server delivers it again the next time the client logs in.

Structr does not pass on the presences that announce whether a contact is available, because every status change of every contact and of every occupant of a joined room would run your method.

Delivery

Structr sends messages, room messages and subscription stanzas after the transaction that sends them has committed. If the transaction fails and is rolled back, nothing is sent, so other people never receive messages about changes that did not happen. If Structr repeats the transaction, for example a REST request whose transaction the database terminated to resolve a deadlock, the stanza is still sent only once.

Since the stanza leaves Structr after the commit, an error during sending does not reach your script. Structr logs it instead. If the client is enabled but not connected, the methods report an error to your script right away. A disabled client sends nothing and reports no error.

Structr runs onXMPPMessage for each incoming message in a transaction of its own. XMPP has no confirmation of received messages, so a message whose method fails is lost, and Structr logs the error. While Structr is not connected, a server that supports offline storage keeps the direct messages for the account and delivers them when the client connects again.

When the client joins a chat room, the server usually sends the most recent messages of the room as history, and onXMPPMessage runs for them as well. Each time the client joins a room again, your method can therefore receive messages it has already processed. Write it so that processing a message twice has the same effect as processing it once.

Related Topics

• Message Brokers - Exchanging data with other systems over MQTT, Kafka and Pulsar
• Business Logic - Implementing the methods onXMPPMessage and onXMPPPresence